'\" t
.TH "SD_BUS_TRACK_ADD_NAME" "3" "" "systemd 256.7" "sd_bus_track_add_name"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
sd_bus_track_add_name, sd_bus_track_add_sender, sd_bus_track_remove_name, sd_bus_track_remove_sender, sd_bus_track_count, sd_bus_track_count_sender, sd_bus_track_count_name, sd_bus_track_contains, sd_bus_track_first, sd_bus_track_next \- Add, remove and retrieve bus peers tracked in a bus peer tracking object
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <systemd/sd\-bus\&.h>
.fi
.ft
.HP \w'int\ sd_bus_track_add_name('u
.BI "int sd_bus_track_add_name(sd_bus_track*\ " "t" ", const\ char*\ " "name" ");"
.HP \w'int\ sd_bus_track_add_sender('u
.BI "int sd_bus_track_add_sender(sd_bus_track*\ " "t" ", sd_bus_message*\ " "message" ");"
.HP \w'int\ sd_bus_track_remove_name('u
.BI "int sd_bus_track_remove_name(sd_bus_track*\ " "t" ", const\ char*\ " "name" ");"
.HP \w'int\ sd_bus_track_remove_sender('u
.BI "int sd_bus_track_remove_sender(sd_bus_track*\ " "t" ", sd_bus_message*\ " "message" ");"
.HP \w'unsigned\ sd_bus_track_count('u
.BI "unsigned sd_bus_track_count(sd_bus_track*\ " "t" ");"
.HP \w'int\ sd_bus_track_count_name('u
.BI "int sd_bus_track_count_name(sd_bus_track*\ " "t" ", const\ char*\ " "name" ");"
.HP \w'int\ sd_bus_track_count_sender('u
.BI "int sd_bus_track_count_sender(sd_bus_track*\ " "t" ", sd_bus_message*\ " "message" ");"
.HP \w'int\ sd_bus_track_contains('u
.BI "int sd_bus_track_contains(sd_bus_track*\ " "t" ", const\ char*\ " "name" ");"
.HP \w'const\ char*\ sd_bus_track_first('u
.BI "const char* sd_bus_track_first(sd_bus_track*\ " "t" ");"
.HP \w'const\ char*\ sd_bus_track_next('u
.BI "const char* sd_bus_track_next(sd_bus_track*\ " "t" ");"
.SH "DESCRIPTION"
.PP
\fBsd_bus_track_add_name()\fR
adds a peer to track to a bus peer tracking object\&. The first argument should refer to a bus peer tracking object created with
\fBsd_bus_track_new\fR(3), the second name should refer to a D\-Bus peer name to track, either in unique or well\-known service format\&. If the name is not tracked yet it will be added to the list of names to track\&. If it already is being tracked and non\-recursive mode is enabled, no operation is executed by this call\&. If recursive mode is enabled a per\-name counter is increased by one each time this call is invoked, and
\fBsd_bus_track_remove_name()\fR
has to be called as many times as
\fBsd_bus_track_add_name()\fR
was invoked before in order to stop tracking of the name\&. Use
\fBsd_bus_track_set_recursive\fR(3)
to switch from the default non\-recursive mode to recursive mode, or back\&. Note that the specified name is tracked as it is, well\-known names are not resolved to unique names by this call\&. Note that multiple bus peer tracking objects may track the same name\&.
.PP
\fBsd_bus_track_remove_name()\fR
undoes the effect of
\fBsd_bus_track_add_name()\fR
and removes a bus peer name from the list of peers to watch\&. Depending on whether non\-recursive or recursive mode is enabled for the bus peer tracking object this call will either remove the name fully from the tracking object, or will simply decrement the per\-name counter by one, removing the name only when the counter reaches zero (see above)\&. Note that a bus peer disconnecting from the bus will implicitly remove its names fully from the bus peer tracking object, regardless of the current per\-name counter\&.
.PP
\fBsd_bus_track_add_sender()\fR
and
\fBsd_bus_track_remove_sender()\fR
are similar to
\fBsd_bus_track_add_name()\fR
and
\fBsd_bus_track_remove_name()\fR
but take a bus message as argument\&. The sender of this bus message is determined and added to/removed from the bus peer tracking object\&. As messages always originate from unique names, and never from well\-known names this means that this call will effectively only add unique names to the bus peer tracking object\&.
.PP
\fBsd_bus_track_count()\fR
returns the number of names currently being tracked by the specified bus peer tracking object\&. Note that this function always returns the actual number of names tracked, and hence if
\fBsd_bus_track_add_name()\fR
has been invoked multiple times for the same name it is only counted as one, regardless if recursive mode is used or not\&.
.PP
\fBsd_bus_track_count_name()\fR
returns the current per\-name counter for the specified name\&. If non\-recursive mode is used this returns either 1 or 0, depending on whether the specified name has been added to the tracking object before, or not\&. If recursive mode has been enabled, values larger than 1 may be returned too, in case
\fBsd_bus_track_add_name()\fR
has been called multiple times for the same name\&.
.PP
\fBsd_bus_track_count_sender()\fR
is similar to
\fBsd_bus_track_count_name()\fR, but takes a bus message object and returns the per\-name counter matching the sender of the message\&.
.PP
\fBsd_bus_track_contains()\fR
may be used to determine whether the specified name has been added at least once to the specified bus peer tracking object\&.
.PP
\fBsd_bus_track_first()\fR
and
\fBsd_bus_track_next()\fR
may be used to enumerate all names currently being tracked by the passed bus peer tracking object\&.
\fBsd_bus_track_first()\fR
returns the first entry in the object, and resets an internally maintained read index\&. Each subsequent invocation of
\fBsd_bus_track_next()\fR
returns the next name contained in the bus object\&. If the end is reached
\fBNULL\fR
is returned\&. If no names have been added to the object yet
\fBsd_bus_track_first()\fR
will return
\fBNULL\fR
immediately\&. The order in which names are returned is undefined; in particular which name is considered the first returned is not defined\&. If recursive mode is enabled and the same name has been added multiple times to the bus peer tracking object it is only returned once by this enumeration\&. If new names are added to or existing names removed from the bus peer tracking object while it is being enumerated the enumeration ends on the next invocation of
\fBsd_bus_track_next()\fR
as
\fBNULL\fR
is returned\&.
.SH "RETURN VALUE"
.PP
On success,
\fBsd_bus_track_add_name()\fR
and
\fBsd_bus_track_add_sender()\fR
return 0 if the specified name has already been added to the bus peer tracking object before and positive if it hasn\*(Aqt\&. On failure, they return a negative errno\-style error code\&.
.PP
\fBsd_bus_track_remove_name()\fR
and
\fBsd_bus_track_remove_sender()\fR
return positive if the specified name was previously tracked by the bus peer tracking object and has now been removed\&. In non\-recursive mode, 0 is returned if the specified name was not being tracked yet\&. In recursive mode
\fB\-EUNATCH\fR
is returned in this case\&. On failure, they return a negative errno\-style error code\&.
.PP
\fBsd_bus_track_count()\fR
returns the number of names currently being tracked, or 0 on failure\&.
.PP
\fBsd_bus_track_count_name()\fR
and
\fBsd_bus_track_count_sender()\fR
return the current per\-name counter for the specified name or the sender of the specified message\&. Zero is returned for names that are not being tracked yet, a positive value for names added at least once\&. Larger values than 1 are only returned in recursive mode\&. On failure, a negative errno\-style error code is returned\&.
.PP
\fBsd_bus_track_contains()\fR
returns the passed name if it exists in the bus peer tracking object\&. On failure, and if the name has not been added yet
\fBNULL\fR
is returned\&.
.PP
\fBsd_bus_track_first()\fR
and
\fBsd_bus_track_next()\fR
return the first/next name contained in the bus peer tracking object, and
\fBNULL\fR
if the end of the enumeration is reached and on error\&.
.SS "Errors"
.PP
Returned errors may indicate the following problems:
.PP
\fB\-EUNATCH\fR
.RS 4
\fBsd_bus_track_remove_name()\fR
or
\fBsd_bus_track_remove_sender()\fR
have been invoked for a name not previously added to the bus peer object\&.
.RE
.PP
\fB\-EINVAL\fR
.RS 4
Specified parameter is invalid\&.
.RE
.PP
\fB\-ENOMEM\fR
.RS 4
Memory allocation failed\&.
.RE
.SH "NOTES"
.PP
Functions described here are available as a shared library, which can be compiled against and linked to with the
\fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
file\&.
.PP
The code described here uses
\fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
\fBsetenv\fR(3)
from a parallel thread\&. It is recommended to only do calls to
\fBsetenv()\fR
from an early phase of the program when no other threads have been started\&.
.SH "HISTORY"
.PP
\fBsd_bus_track_add_name()\fR,
\fBsd_bus_track_add_sender()\fR,
\fBsd_bus_track_remove_name()\fR,
\fBsd_bus_track_remove_sender()\fR,
\fBsd_bus_track_count()\fR,
\fBsd_bus_track_count_name()\fR,
\fBsd_bus_track_count_sender()\fR,
\fBsd_bus_track_contains()\fR,
\fBsd_bus_track_first()\fR, and
\fBsd_bus_track_next()\fR
were added in version 232\&.
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_track_new\fR(3)
